References

System Types

System types are built-in types that provide core functionality in Structr. They include types for users and groups, files and folders, pages and templates, email handling, and more. Each system type comes with predefined properties and methods. You can use these types directly or extend them in your schema to add custom properties and behavior. For details on extending types, see the Data Model chapter.

DataFeed

Fetches and stores content from RSS and Atom feeds. Structr periodically checks configured feeds and creates FeedItem objects for new entries. Key properties include url for the feed location, updateInterval for automatic refresh timing, lastUpdated for tracking, and maxItems and maxAge for limiting stored entries.

Details

Feed items include title, author, publication date, content, and any enclosures like images or audio files. The updateIfDue() method checks whether enough time has passed since the last fetch and updates only when necessary. Use cleanUp() to remove old items based on your retention settings. You can extend DataFeed or FeedItem with custom properties and add an onCreate method on FeedItem to process new entries automatically – for example, sending notifications or importing content into your application.

Methods

Name	Description
`cleanUp()`	Removes old feed items based on the configured maxItems and maxAge properties.
`updateFeed()`	Fetches new entries from the remote feed URL and runs cleanUp afterward.
`updateIfDue()`	Checks if an update is due based on lastUpdated and updateInterval, and fetches new items if necessary.

Markdown Rendering Hint: Children of SystemType(DataFeed) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

EMailMessage

Stores email messages fetched from mailboxes or saved from outgoing mail. Key properties include subject, from, fromMail, to, cc, bcc, content (plain text), htmlContent, sentDate, receivedDate, messageId, inReplyTo for threading, header (all headers as JSON), mailbox, and attachedFiles.

Details

Attachments are stored as linked File objects in a date-based folder structure. Add an onCreate method to process incoming emails automatically – for example, creating support tickets. You can extend EMailMessage with custom properties and configure the subtype on the Mailbox via overrideMailEntityType.

Properties

Name	Type	Description
`attachedFiles`	`File[]`	Files that were attached to this message.
`bcc`	`String`	BCC address of this message.
`cc`	`String`	CC address of this message.
`content`	`String`	Plaintext content of this message.
`from`	`String`	Sender name of this message.
`fromMail`	`String`	Sender address of this message.
`htmlContent`	`String`	HTML content of this message.
`inReplyTo`	`String`	inReplyTo of this message.
`mailbox`	`Mailbox`	Mailbox this message belongs to.
`messageId`	`String`	Message id of this message.
`receivedDate`	`Date`	Date this message was received.
`replyTo`	`String`	Reply address of this message.
`sentDate`	`Date`	Date this message was sent.
`subject`	`String`	Subject of this message.
`to`	`String`	Recipient of this message.

Markdown Rendering Hint: Children of SystemType(EMailMessage) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

File

Represents files in Structr’s virtual filesystem. Files can live on different storage backends – local disk, Amazon S3, or archive systems – while keeping consistent metadata and permissions. Key properties include name, contentType for MIME type, size, parent for folder location, and isTemplate for dynamic content evaluation.

Details

Structr automatically calculates checksums, extracts text via Apache Tika for full-text search, and supports OCR when Tesseract is installed. Files use the same permission system as all other objects. You can extend the File type with custom properties or create subtypes like InvoiceDocument or ProductImage.

Methods

Name	Description
`doCSVImport()`	Starts an asynchronous CSV import job and returns the job ID.
`doXMLImport()`	Starts an asynchronous CSV import job and returns the job ID.
`getCSVHeaders()`	Extracts and returns the column headers from a CSV file.
`getFirstLines()`	Returns the first lines of the file along with the detected line separator (LF, CR, or CR+LF).
`getSearchContext()`	Searches for a term in the file’s extracted text content and returns the surrounding context.
`getXMLStructure()`	Analyzes the structure of an XML file and returns it as a JSON representation.

Properties

Name	Type	Description
`checksum`	`Long`	xxHash checksum of the file’s content (generated automatically).
`contentType`	`String`	Content type of the file.
`crc32`	`Long`	CRC32 checksum of the file’s content (optional, see below).
`isTemplate`	`Boolean`	When checked, the content of this file is evaluated as a script and the resulting content is returned.
`md5`	`String`	MD5 checksum of the file’s content (optional, see below).
`parent`	`Folder`	parent folder of this File or Folder
`path`	`String`	full path of this file or folder (read-only)
`sha1`	`String`	SHA1 checksum of the file’s content (optional, see below).
`sha512`	`String`	SHA512 checksum of the file’s content (optional, see below).
`size`	`Long`	Size of this file.

Markdown Rendering Hint: Children of SystemType(File) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Folder

Represents directories in Structr’s virtual filesystem. The folder structure you see is independent of where files are physically stored – you can reorganize freely without moving actual data. Key properties include name, parent for the containing folder, and children for contained files and subfolders.

Details

You can mount folders to external storage locations like local directories or cloud providers, with automatic change detection. Each folder can use a different storage backend, so frequently accessed files can live on fast storage while archives go somewhere cheaper. Permissions on folders affect visibility of their contents. You can extend the Folder type or create subtypes for specialized use cases.

Properties

Name	Type	Description
`enabledChecksums`	`String`	Override for the global checksums setting, allows you to enable or disable individual checksums for all files in this folder (and sub-folders).
`parent`	`Folder`	parent folder of this File or Folder
`path`	`String`	full path of this file or folder (read-only)

Markdown Rendering Hint: Children of SystemType(Folder) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Group

Organizes users for easier permission management. Instead of granting permissions to individual users, you grant them to groups – when a user joins a group, they automatically inherit all its permissions. Key properties include name and members for the collection of users and nested groups.

Details

Groups can contain other groups, so you can build hierarchies where permissions flow down automatically. In the Admin UI, you manage membership via drag-and-drop. Groups also serve as integration points for LDAP, letting you map external directory groups to Structr. You can extend the Group type or create subtypes like Department or Team.

Properties

Name	Type	Description
`members`	`Principal[]`	Members of the group, can be User or Group.

Markdown Rendering Hint: Children of SystemType(Group) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Image

Extends File with specialized image handling. When you upload an image, Structr automatically extracts EXIF metadata (camera info, GPS coordinates, date taken) and stores the dimensions. Two thumbnails are generated on first access and linked to the original via database relationships.

Details

Supported formats include JPEG, PNG, GIF, WebP, and TIFF. You can scale, crop, and convert between formats. The Admin UI offers a built-in image editor and an optimized view mode for browsing image folders. With Tesseract OCR installed, Structr can extract text from images for full-text search. You can extend Image or create subtypes like ProductImage.

Methods

Name	Description
`doCSVImport()`	Starts an asynchronous CSV import job and returns the job ID.
`doXMLImport()`	Starts an asynchronous CSV import job and returns the job ID.
`getCSVHeaders()`	Extracts and returns the column headers from a CSV file.
`getFirstLines()`	Returns the first lines of the file along with the detected line separator (LF, CR, or CR+LF).
`getSearchContext()`	Searches for a term in the file’s extracted text content and returns the surrounding context.
`getXMLStructure()`	Analyzes the structure of an XML file and returns it as a JSON representation.

Properties

Name	Type	Description
`checksum`	`Long`	xxHash checksum of the file’s content (generated automatically).
`contentType`	`String`	Content type of the file.
`crc32`	`Long`	CRC32 checksum of the file’s content (optional, see below).
`exifIFD0Data`	`String`	Exif IFD0 data.
`exifSubIFDData`	`String`	Exif SubIFD data.
`gpsData`	`String`	GPS data.
`height`	`Integer`	Height of this image.
`isTemplate`	`Boolean`	When checked, the content of this file is evaluated as a script and the resulting content is returned.
`md5`	`String`	MD5 checksum of the file’s content (optional, see below).
`orientation`	`Integer`	Orientation of this image.
`parent`	`Folder`	parent folder of this File or Folder
`path`	`String`	full path of this file or folder (read-only)
`sha1`	`String`	SHA1 checksum of the file’s content (optional, see below).
`sha512`	`String`	SHA512 checksum of the file’s content (optional, see below).
`size`	`Long`	Size of this file.
`width`	`Integer`	Width of this image.

Markdown Rendering Hint: Children of SystemType(Image) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

MailTemplate

Defines reusable email content for automated messages like registration confirmations or password resets. Key properties include name for referencing in code, locale for language variants, and content fields for subject, plain text, and HTML body. Use ${...} expressions for dynamic values like ${link} or ${me.name}.

Details

Structr uses predefined template names for built-in workflows: CONFIRM_REGISTRATION_* for self-registration and RESET_PASSWORD_* for password reset. The Admin UI provides a Template Wizard that generates these automatically, plus a visual editor with live preview. Each template can have multiple locale variants for multi-language support.

Properties

Name	Type	Description
`description`	`String`	Description of this template.
`locale`	`String`	Locale for this template.
`text`	`String`	Text content of this template.

Markdown Rendering Hint: Children of SystemType(MailTemplate) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Mailbox

Configures an email account for automatic fetching from IMAP or POP3 servers. The MailService periodically checks all mailboxes and stores new messages as EMailMessage objects. Key properties include host, mailProtocol (imaps or pop3), port, user, password, and folders to monitor.

Details

The service fetches messages newest first, detects duplicates via Message-ID, and extracts attachments as File objects. Use overrideMailEntityType to specify a custom subtype for incoming emails, enabling lifecycle methods for automatic processing. You can trigger immediate fetching with FetchMailsCommand or list available folders with FetchFoldersCommand.

Methods

Name	Description
`fetchMails()`	Triggers an immediate fetch of emails from this mailbox, bypassing the regular MailService interval. Creates EMailMessage objects for new messages and extracts attachments.
`getAvailableFoldersOnServer()`	Returns a list of folder names available on the configured mail server. Use this to discover which folders can be added to the folders property for fetching.

Properties

Name	Type	Description
`emails`	`EMailMessage[]`	Messages in this mailbox.
`folders`	`String[]`	Folders this mailbox queries.
`host`	`String`	Host or IP address this mailbox connects to.
`mailProtocol`	`Enum`	Mail protocol.
`password`	`String`	Password this mailbox connects with.
`port`	`Integer`	Port this mailbox connects to.
`user`	`String`	Username this mailbox connects with.

Markdown Rendering Hint: Children of SystemType(Mailbox) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

MessageClient

Methods

Name	Description
`sendMessage()`	Sends a message to the specified topic.
`subscribeTopic()`	Subscribes the client to the specified topic to receive messages.
`unsubscribeTopic()`	Unsubscribes the client from the specified topic.

Markdown Rendering Hint: Children of SystemType(MessageClient) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Page

Represents a complete web page. Structr renders pages on the server, so browsers receive ready-to-display HTML rather than JavaScript that builds the page client-side. Key properties include name (also determines the URL), contentType for output format, position for start page selection, showOnErrorCodes for error pages, and sites for multi-site hosting.

Details

Pages support template expressions for dynamic content, repeaters for collections, partial reloads without full page refresh, and show/hide conditions. Permissions control both data access and what renders – you can make entire page sections visible only to certain users. URL Routing lets you define custom paths with typed parameters that Structr validates automatically.

Properties

Name	Type	Description
`data-structr-id`	`String`	Set to ${current.id} most of the time.
`hideConditions`	`String`	Conditions which have to be met in order for the element to be hidden. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.
`sharedComponentConfiguration`	`String`	The contents of this field will be evaluated before rendering this component. This is usually used to customize shared components to make them more flexible. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.
`showConditions`	`String`	Conditions which have to be met in order for the element to be shown. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.

Markdown Rendering Hint: Children of SystemType(Page) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Site

Controls which pages are served for which domain. A single Structr instance can host multiple websites – useful for running public and internal sites side by side, serving localized versions under country domains, or operating staging and production on the same server. Key properties include name, hostname, and an optional port for exact matching.

Details

When a request arrives, Structr checks hostname and port against configured sites and serves only the assigned pages. Pages without site assignment are served everywhere (the default behavior). A page can belong to multiple sites. Sites control page visibility only – files remain accessible regardless of domain. Site configurations are included in deployment exports.

Properties

Name	Type	Description
`hostname`	`String`	Domain name used to match incoming requests to this site. Requests with a matching Host header are routed to pages assigned to this site.
`port`	`Integer`	Port number used together with hostname to match incoming requests. Allows hosting multiple sites on different ports of the same domain.

Markdown Rendering Hint: Children of SystemType(Site) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Template

Contains text or markup that outputs directly into pages. Unlike HTML elements, templates give you full control over where children appear – you call render(children) explicitly. This lets you define layouts with multiple insertion points like sidebars and main content areas. Key properties include name, content, contentType (Markdown, AsciiDoc, HTML, JSON, XML, plaintext), and repeater settings.

Details

The render() function controls exactly where each child appears, while include() pulls content from elsewhere in the page tree. The Main Page Template typically sits below the Page element and defines the overall structure. Templates can also produce non-HTML output by setting the content type to application/json or text/xml.

Properties

Name	Type	Description
`data-structr-id`	`String`	Set to ${current.id} most of the time.
`hideConditions`	`String`	Conditions which have to be met in order for the element to be hidden. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.
`sharedComponentConfiguration`	`String`	The contents of this field will be evaluated before rendering this component. This is usually used to customize shared components to make them more flexible. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.
`showConditions`	`String`	Conditions which have to be met in order for the element to be shown. This is an ‘auto-script’ environment, meaning that the text is automatically surrounded with ${}.

Markdown Rendering Hint: Children of SystemType(Template) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

User

Represents user accounts in your application. Every request to Structr runs in the context of a user – either authenticated or anonymous. Users can log in via HTTP headers, session cookies, JWT tokens, or OAuth providers. Key properties include name and eMail for identification, password (stored as secure hash), isAdmin for full system access, blocked for disabling accounts, and locale for localization.

Details

Structr supports two-factor authentication via TOTP and automatically locks accounts after too many failed login attempts. For self-service scenarios, users can register themselves and confirm their account via email. You can extend the User type with custom properties or create subtypes like Employee or Customer.

Properties

Name	Type	Description
`confirmationKey`	`String`	Temporary token for email verification during self-registration. Set automatically when a user registers and cleared after successful confirmation.
`homeDirectory`	`Folder`	The home directory of this user, if `application.filesystem.enabled` is set to `true` in `structr.conf`.
`skipSecurityRelationships`	`Boolean`	When true, excludes this user from relationship-based permission checks. Useful for system users or service accounts that should bypass normal access control evaluation.
`workingDirectory`	`Folder`	The work directory of this user, if `application.filesystem.enabled` is set to `true` in `structr.conf`.

Markdown Rendering Hint: Children of SystemType(User) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.

Widget

Provides reusable building blocks for pages – from simple HTML snippets to complete configurable components. Structr parses the widget’s HTML source when you insert it into a page. Key properties include name, source for HTML content, configuration for customizable variables (JSON), selectors for context menu suggestions, treePath for categories, and isPageTemplate for page creation.

Details

Template expressions in square brackets like [variableName] become configurable options that users fill in when inserting. The configuration JSON defines input types, defaults, and help text. Widgets can define shared components with <structr:shared-template> tags. The Widgets flyout shows both local and remote widgets, enabling sharing across applications.

Properties

Name	Type	Description
`configuration`	`String`	JSON object defining configurable template variables. Keys match square bracket expressions in the source, values define input labels and types for the insertion dialog.
`description`	`String`	Explanatory text displayed when inserting the Widget. Supports HTML formatting. Shown in the dialog when the Widget is used as a page template.
`isPageTemplate`	`Boolean`	When enabled, this Widget appears in the Create Page dialog as a page template option.
`selectors`	`String[]`	CSS selectors that control where this Widget appears as a suggestion in the context menu. For example “table” or “div.container”.
`source`	`String`	HTML source code of the Widget. Can include Structr expressions and template variables in square brackets like [variableName].
`svgIconPath`	`String`	Path to an SVG icon displayed in the Widgets flyout, can be an absolute URL.
`thumbnailPath`	`String`	Path to a thumbnail image displayed in the Widgets flyout, can be an absolute URL.
`treePath`	`String`	Slash-separated path for organizing Widgets into categories. Must begin with a slash, for example “/Forms/Input Elements”.

Markdown Rendering Hint: Children of SystemType(Widget) not rendered because SystemTypeMarkdownFormatter prevents rendering of children.